home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / gawk213b.zoo / gawk.man < prev    next >
Text File  |  1991-08-04  |  38KB  |  961 lines
  1.  
  2.  
  3.  
  4. GAWK(1)                 Utility Commands                  GAWK(1)
  5.  
  6.  
  7. NAME
  8.      gawk - pattern scanning and processing language
  9.  
  10. SYNOPSIS
  11.      gawk [ -W gawk-options ] [ -Ffs ] [ -v var=val ] -f
  12.      program-file [ -- ] file ...
  13.      gawk [ -W gawk-options ] [ -Ffs ] [ -v var=val ] [ -- ]
  14.      program-text file ...
  15.  
  16. DESCRIPTION
  17.      Gawk is the GNU Project's implementation of the AWK program-
  18.      ming language.  It conforms to the definition of the
  19.      language in the POSIX P1003.2 Command Language And Utilities
  20.      Standard (draft 11).  This version in turn is based on the
  21.      description in The AWK Programming Language, by Aho, Ker-
  22.      nighan, and Weinberger, with the additional features defined
  23.      in the System V Release 4 version of UNIX awk.  Gawk also
  24.      provides some GNU-specific extensions.
  25.  
  26.      The command line consists of options to gawk itself, the AWK
  27.      program text (if not supplied via the -f option), and values
  28.      to be made available in the ARGC and ARGV pre-defined AWK
  29.      variables.
  30.  
  31.      Gawk accepts the following options, which should be avail-
  32.      able on any implementation of the AWK language.
  33.  
  34.      -Ffs Use fs for the input field separator (the value of the
  35.           FS predefined variable).
  36.  
  37.      -v var=val
  38.           Assign the value val, to the variable var, before exe-
  39.           cution of the program begins.  Such variable values are
  40.           available to the BEGIN block of an AWK program.
  41.  
  42.      -f program-file
  43.           Read the AWK program source from the file program-file,
  44.           instead of from the first command line argument.  Mul-
  45.           tiple -f options may be used.
  46.  
  47.      --   Signal the end of options. This is useful to allow
  48.           further arguments to the AWK program itself to start
  49.           with a ``-''.  This is mainly for consistency with the
  50.           argument parsing convention used by most other POSIX
  51.           programs.
  52.  
  53.      Following the POSIX standard, gawk-specific options are sup-
  54.      plied via arguments to the -W option.  Multiple -W options
  55.      may be supplied, or multiple arguments may be supplied
  56.      together if they are separated by commas, or enclosed in
  57.      quotes and separated by white space.  Case is ignored in
  58.      arguments to the -W option.  Gawk recognizes the following
  59.      arguments to -W:
  60.  
  61.      compat    Run in compatibility mode.  In compatibility mode,
  62.                gawk behaves identically to UNIX awk; none of the
  63.                GNU-specific extensions are recognized.
  64.  
  65.      copyleft
  66.      copyright Print the short version of the GNU copyright
  67.                information message on the error output.
  68.  
  69.      version   Print version information for this particular copy
  70.                of gawk on the error output.  This is useful
  71.                mainly for knowing if the current copy of gawk on
  72.                your system is up to date with respect to whatever
  73.                the Free Software Foundation is distributing.
  74.  
  75.      posix     This turns on compatibility mode, with the follow-
  76.                ing additional restrictions:
  77.  
  78.                o    \x escape sequences are not recognized.
  79.  
  80.                o    The synonym func for the keyword function is
  81.                     not recognized.
  82.  
  83.                o    The operators ** and **= can not be used in
  84.                     place of ^ and ^=.
  85.  
  86.      lint      Provide warnings about constructs that are dubious
  87.                or non-portable to other AWK implementations.
  88.  
  89.      Any other options are flagged as illegal, but are otherwise
  90.      ignored.
  91.  
  92. AWK PROGRAM EXECUTION
  93.      An AWK program consists of a sequence of pattern-action
  94.      statements and optional function definitions.
  95.  
  96.           pattern   { action statements }
  97.           function name(parameter list) { statements }
  98.  
  99.      Gawk first reads the program source from the program-file(s)
  100.      if specified, or from the first non-option argument on the
  101.      command line.  The -f option may be used multiple times on
  102.      the command line.  Gawk will read the program text as if all
  103.      the program-files had been concatenated together.  This is
  104.      useful for building libraries of AWK functions, without hav-
  105.      ing to include them in each new AWK program that uses them.
  106.      To use a library function in a file from a program typed in
  107.      on the command line, specify /dev/tty as one of the
  108.      program-files, type your program, and end it with a ^D
  109.      (control-d).
  110.  
  111.      The environment variable AWKPATH specifies a search path to
  112.      use when finding source files named with the -f option.  If
  113.      this variable does not exist, the default path is
  114.      ".:/usr/lib/awk:/usr/local/lib/awk".  If a file name given
  115.      to the -f option contains a ``/'' character, no path search
  116.      is performed.
  117.  
  118.      Gawk executes AWK programs in the following order.  First,
  119.      gawk compiles the program into an internal form.  Next, all
  120.      variable assignments specified via the -v option are per-
  121.      formed.  Then, gawk executes the code in the BEGIN block(s)
  122.      (if any), and then proceeds to read each file named in the
  123.      ARGV array.  If there are no files named on the command
  124.      line, gawk reads the standard input.
  125.  
  126.      If a ``file'' named on the command line has the form var=val
  127.      it is treated as a variable assignment. The variable var
  128.      will be assigned the value val.  This is most useful for
  129.      dynamically assigning values to the variables AWK uses to
  130.      control how input is broken into fields and records. It is
  131.      also useful for controlling state if multiple passes are
  132.      needed over a single data file.
  133.  
  134.      If the value of a particular element of ARGV is empty (""),
  135.      gawk skips over it.
  136.  
  137.      For each line in the input, gawk tests to see if it matches
  138.      any pattern in the AWK program.  For each pattern that the
  139.      line matches, the associated action is executed.  The pat-
  140.      terns are tested in the order they occur in the program.
  141.  
  142.      Finally, after all the input is exhausted, gawk executes the
  143.      code in the END block(s) (if any).
  144.  
  145. VARIABLES AND FIELDS
  146.      AWK variables are dynamic; they come into existence when
  147.      they are first used. Their values are either floating-point
  148.      numbers or strings, or both, depending upon how they are
  149.      used. AWK also has one dimension arrays; multiply dimen-
  150.      sioned arrays may be simulated.  There are several pre-
  151.      defined variables that AWK sets as a program runs; these
  152.      will be described as needed and summarized below.
  153.  
  154.      Fields
  155.  
  156.      As each input line is read, gawk splits the line into
  157.      fields, using the value of the FS variable as the field
  158.      separator.  If FS is a single character, fields are
  159.      separated by that character.  Otherwise, FS is expected to
  160.      be a full regular expression.  In the special case that FS
  161.      is a single blank, fields are separated by runs of blanks
  162.      and/or tabs.  Note that the value of IGNORECASE (see below)
  163.      will also affect how fields are split when FS is a regular
  164.      expression.
  165.  
  166.      If the FIELDWIDTHS variable is set to a space separated list
  167.      of numbers, each field is expected to have fixed width, and
  168.      gawk will split up the record using the specified widths.
  169.      The value of FS is ignored.
  170.  
  171.      Each field in the input line may be referenced by its posi-
  172.      tion, $1, $2, and so on.  $0 is the whole line. The value of
  173.      a field may be assigned to as well.  Fields need not be
  174.      referenced by constants:
  175.  
  176.           n = 5
  177.           print $n
  178.  
  179.      prints the fifth field in the input line.  The variable NF
  180.      is set to the total number of fields in the input line.
  181.  
  182.      References to non-existent fields (i.e. fields after $NF),
  183.      produce the null-string. However, assigning to a non-
  184.      existent field (e.g., $(NF+2) = 5) will increase the value
  185.      of NF, create any intervening fields with the null string as
  186.      their value, and cause the value of $0 to be recomputed,
  187.      with the fields being sepa